Docker Deployment

Deploy the Stripe Payments API using Docker and Docker Compose

This guide covers deploying the Stripe Payments API using Docker, including local development with Docker Compose and pulling the pre-built image from Docker Hub.

Overview

The API is containerized using Docker with a production-ready configuration. A pre-built image is available on Docker Hub for quick deployment.

Docker Hub Image

luis159/stripe-back:latest

Base Image

node:20-alpine

Dockerfile Configuration

The API uses an optimized Dockerfile for production deployments:

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --omit=dev

COPY . .

ENV NODE_ENV=production
ENV PORT=3000

EXPOSE 3000

CMD ["npm", "start"]

Key Features:

• Uses Alpine Linux for minimal image size
• Installs only production dependencies with npm ci --omit=dev
• Sets production environment by default
• Exposes port 3000
• Runs with npm start command

Method 1: Docker Compose (Local Development)

The recommended approach for local development is using Docker Compose.

1. Create Environment File
2. Create a .env file in your project root with your Stripe credentials:
3. STRIPE_SECRET_KEY=sk_test_xxxxxxxxxxxxx
   STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxx
   PORT=3000
   NODE_ENV=production
   

4. Never commit your .env file to version control. Add it to .gitignore.

5. Docker Compose Configuration
6. The docker-compose.yml file is configured as follows:
7. services:
     api:
       build: .
       container_name: stripe-back-api
       env_file:
         - .env
       ports:
         - "3000:3000"
       restart: unless-stopped
   

8. Configuration Details:
10. Start the Application
11. docker-compose up -d
    

12. The -d flag runs the container in detached mode (background).
13. View Logs
14. docker-compose logs -f api
    

15. Stop the Application
16. docker-compose down
    

Method 2: Pre-built Docker Hub Image

For quick deployment without building from source, use the pre-built image.

1. Pull the Image
2. docker pull luis159/stripe-back:latest
   

3. Run the Container
4. docker run -d \
     --name stripe-back-api \
     -p 3000:3000 \
     -e STRIPE_SECRET_KEY=sk_test_xxxxxxxxxxxxx \
     -e STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxx \
     -e NODE_ENV=production \
     --restart unless-stopped \
     luis159/stripe-back:latest
   

5. Parameters:
7. Using Environment File
8. Alternatively, use an environment file:
9. docker run -d \
     --name stripe-back-api \
     -p 3000:3000 \
     --env-file .env \
     --restart unless-stopped \
     luis159/stripe-back-api:latest
   

10. Verify the Container
11. docker ps
    

12. Expected Output:
13. CONTAINER ID   IMAGE                        STATUS         PORTS
    abc123def456   luis159/stripe-back:latest   Up 10 seconds  0.0.0.0:3000->3000/tcp
    

14. View Container Logs
15. docker logs -f stripe-back-api
    

Method 3: Build from Source

If you need to customize the image or work with local changes:

1. Clone the Repository
2. git clone <repository-url>
   cd stripe-back
   

3. Build the Image
4. docker build -t stripe-back:local .
   

5. Run Your Custom Image
6. docker run -d \
     --name stripe-back-api \
     -p 3000:3000 \
     --env-file .env \
     --restart unless-stopped \
     stripe-back:local
   

Environment Variables

Required environment variables for deployment:

Variable	Description	Required	Example
STRIPE_SECRET_KEY	Stripe API secret key	Yes	sk_test_...
STRIPE_WEBHOOK_SECRET	Webhook signing secret	Yes	whsec_...
PORT	Application port	No	3000 (default)
NODE_ENV	Node environment	No	production (default)

The Dockerfile sets NODE_ENV=production and PORT=3000 by default. You can override these with environment variables.

Health Check

Verify the API is running:

curl http://localhost:3000/

Expected Response:

{
  "status": true,
  "message": "API is running"
}

Production Deployment Tips

Use Specific Tags

Instead of latest, use specific version tags in production:

docker pull luis159/stripe-back:v1.0.0

Resource Limits

Set memory and CPU limits for production:

docker run -d \
  --memory="512m" \
  --cpus="1.0" \
  luis159/stripe-back:latest

Volume Mounting

If your app needs persistent storage:

docker run -d \
  -v /path/on/host:/app/data \
  luis159/stripe-back:latest

Network Configuration

For multi-container setups, use Docker networks:

docker network create stripe-network
docker run -d --network stripe-network luis159/stripe-back:latest

Docker Compose for Production

For production deployments with additional services:

docker-compose.prod.yml

services:
  api:
    image: luis159/stripe-back:latest
    container_name: stripe-back-api
    env_file:
      - .env.production
    ports:
      - "3000:3000"
    restart: always
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Deploy with:

docker-compose -f docker-compose.prod.yml up -d

Troubleshooting

Container exits immediately

Check the logs for errors:

docker logs stripe-back-api

Common issues:

• Missing required environment variables
• Port 3000 already in use
• Invalid Stripe credentials

Cannot connect to the API

1. Verify the container is running: docker ps
2. Check port mapping: docker port stripe-back-api
3. Test from inside the container:
   docker exec stripe-back-api curl http://localhost:3000
   

Environment variables not loading

Ensure your .env file:

• Is in the same directory as your docker-compose.yml
• Has no quotes around values (unless needed)
• Uses the correct variable names
• Has Unix line endings (LF, not CRLF)

Build fails with dependency errors

If building from source fails:

# Clear Docker cache and rebuild
docker build --no-cache -t stripe-back:local .

Container Management

Common Commands

# Stop container
docker stop stripe-back-api

# Start container
docker start stripe-back-api

# Restart container
docker restart stripe-back-api

# Remove container
docker rm stripe-back-api

# Remove image
docker rmi luis159/stripe-back:latest

# Execute command in container
docker exec -it stripe-back-api sh

# View resource usage
docker stats stripe-back-api

Next Steps

• Configure webhook testing in your Docker environment
• Review error handling patterns
• Follow the complete payment workflow